Treweler Documentation

Treweler is a flexible and multipurpose WordPress plugin based on the Mapbox web mapping platform. Its purpose is to help you create a custom map for your personal or business project. This combination of plugin functionality and Mapbox map customization provides limitless possibilities when creating a way to describe the world around us.

This document covers the plugin installation and how to use it. Although all functions and settings of the plugin can be quite intuitive, we still encourage you to read this document thoroughly before using the plugin for the first time as to avoid any difficulties in the future.

Thank you for purchasing our product!

Requirements

Since WordPress is a MySQL and PHP platform, you need to have a hosting server prepared for it. In case you already have a hosting server, you need to check whether it is compatible with WordPress hosting requirements or not.

For installing this plugin you need to make sure that you have the following extensions on your web server. If you do not have them, you will need to contact your web hosting provider.

1. PHP version 5.6 or greater.
2. WordPress version 5.7 or greater.
3. Activated JavaScript and Cookies in your browser.

Plugin Download

You need to download all plugin files after purchasing them. If you purchased the plugin on CodeCanyon, please read this article to understand how to download your item.

Install & Activate

If you have a server with WordPress installed on it and you have downloaded all the necessary files, then you are ready to install and activate the plugin.

Automatic Plugin Installation

Since you already downloaded the plugin zip file, you can manually upload and install it through the plugin’s admin screen. To add the plugin using the built-in plugin installer:

1. Login to your WordPress admin panel.
2. Navigate your way to the Plugins menu and click Add New.
3. Click the Upload Plugin button at the top of the screen, and select the zip file from your computer.
4. Finally, click the Install Now button.

When installation is complete, you’ll see “Plugin Installed Successfully.” Click the Activate Plugin button at the bottom of the page.

Manual Plugin Installation

In rare cases, you may need to install a plugin by manually transferring the files onto the server. This is recommended only when absolutely necessary, such as when your server is not configured to allow automatic installations. This procedure requires you to be familiar with the process of transferring files using an SFTP client.

1. First of all, unzip the previously downloaded plugin zip archive. You should see a single folder named after the plugin.
2. Connect to your WordPress server with your SFTP client.
3. Copy the plugin folder to the wp-content/plugins folder in your WordPress directory. This installs the plugin to your WordPress site.
4. Navigate to your Plugins admin screen and locate the newly uploaded plugin in the list.
5. Click the plugin’s Activate link.

Plugin Updating

To update the plugin, navigate to the Plugins menu in the website admin panel. Click the Deactivate link next to the plugin name and then click the Delete link to remove the plugin. Install the new version of the plugin following the instructions in the "Install & Activate" section of this documentation.

General Settings

Mapbox Access Token

The first thing you should do after installing and activating the plugin is to add the Mapbox Access Token to the main plugin settings.

To get a token you should register on the Mapbox Website and create a new token on your Access Tokens Page. For information regarding management of the Mapbox Access Tokens, please read this article.

After you have created an Access Token, go to the Treweler menu in the admin panel, click the Settings, open the General tab and paste a token to the Access Token filed. Click the Save Changes button to save the settings.

Now you can create maps and publish them on the pages of your website.

Additional CSS

To add custom CSS code, go to the Treweler menu in the admin panel, click the Settings, open the Additional CSS tab and paste your code to the code editor. Click the Save Changes button to apply the code.

Maps

Maps are the basis for realizing your ideas and shaping them accordingly. In order to create one, you will need to:

1. Navigate to the Treweler menu in the admin panel.
2. Click Maps and click the Add New button at the top of the page.

Map Settings

Map settings include a lot of different options, so let's take a look at each of them.

Styles. As far as this feature goes, it includes several built-in map styles, so you can easily choose a style that you like or the one that suits your project goals. Once you have, changes will appear immediately in the map preview.

Custom Styles. The plugins allow you to add custom map styles created in the Mapbox Studio style editor or copied from other sources.

When it comes to custom map styles, they are a powerful tool that breathe life into your ideas. To make things easier for you, we have prepared several custom styles, so that you only copy them to your account and use them for your projects. Besides, you may have seen some of them on our demo maps already.

If you wish to copy the style you like to your account, just click the style link and click Copy in the bottom right corner of the page. Once that’s done, you have your custom style.

Initial Point. This feature shows you the initial geographical center point of your map. From this point forth, you can set the latitude and longitude manually or use the map preview by enabling the "Use the map preview" checkbox.

Initial Zoom Level. A zoom level determines how much of the world is visible on a map. Mapbox provides maps in 23 zoom levels, with 0 being the lowest zoom level (fully zoomed out) and 22 being the highest (fully zoomed in). At low zoom levels, a small set of map tiles covers a large geographical area. At higher zoom levels, a larger number of tiles cover a smaller geographical area.

Zoom Range. Zoom range lets you set the minimum and maximum possible map zoom levels.

Overlay Color. With this setting, it's possible to add a custom overlay color with the necessary opacity above the main map.

Render World Copies. Activate this checkbox to switch between rendering a single world and multiple copies of the world. Once you have, changes will appear immediately in the map preview.

Map Details

General. This is where you give a personal touch to your map, as it allows you to add a title, description and logo for the map. In addition to that, you can also change the text style and position of the elements by using additional settings.

Also in this section you can use the following settings:

• Select projection of the map.
• Enable map centering on click.
• Enable the marker at the click point on the map and select its style.
• Add one or more custom CSS classes separated by spaces.

Categories. Categories provide a helpful way to group related Markers and Routes together. Using these settings, you can enable or disable the categories drop-down list, as well as change its position on the map. In the related sections, we will tell you how to assign categories to Maps and Routes.

Controls. You can use these settings to add different controls to the map and change their position. Any changes appear immediately in the map preview.

Layers. By adjusting these settings, you have the ability to disable layer groups in both classic Mapbox map styles and the Standard Mapbox map style. To modify the visibility settings of custom style layers, use Mapbox Studio.

Geolocation. Settings to obtain the user's current geolocation.

Attribution. Mapbox maps require two types of attribution: a logo and text attribution. This is a group of settings that helps you manage these attributes.

Clustering. Often, a map can show too much data at a single time. Markers overlap with each other. The map looks and feels cluttered. Enabling clustering in this group of settings helps to avoid this problem.

Languages. When building a map from a Mapbox template style, map labels will appear in English by default. If you wish to change the language of your map's labels, you can easily do that by directly going to the Mapbox Studio style editor or dynamically using plugin settings. Unfortunately, not all built-in map styles support languages well, so we recommend creating your own map style if you need to use a language other than English.

Information Widgets. You can place additional information or interesting facts on the map, using Information widgets. With these settings, it is possible to create text widgets, change their position and place a color gradient on either side of the map.

Pitch & Bearing. The pitch is the angle towards the horizon measured in degrees with a range between 0 and 60 degrees. The bearing is the compass direction that is "up". For example, bearing: 90 orient the map so that east is up.

Restrict Panning. Use these settings to disable map panning or restrict it to an area.

Preloader. Using these settings, you can enable the progress preloader with logo and text information that will appear until the entire map is loaded.

Tour. Tour settings allow you to impressively switch between markers using one of the animation types, Jump or Fly. However, make sure that at least one marker is created to start using these settings.

Marker Locator. Use the Marker Locator to display map markers within the user's vicinity, or in the vicinity of the area on the map that the user chooses. The user's position can be determined automatically, or set manually by clicking on the map, or by using an intuitive address search with auto-completion. The number of displayed markers can be sorted by distance, either in kilometers or miles.

For more information regarding the configuration of the Marker Locator, please refer to the relevant section in the documentation.

Boundaries. Treweler Boundaries is a set of global country and region boundary data with different levels of accuracy. This feature allows you to build and customize any combination of countries or regions, as well as change their style or add interactivity for each data polygon. Use Treweler Boundaries and explore interesting options in presenting and visualizing data on the map.

Map Shortcode

When it comes to inserting the map anywhere on your pages, this setting will be your utmost friend. To help you understand it a bit more, we will be explaining how to insert a map using shortcode down below in the "Maps Publishing" section of this documentation.

Markers

Markers are the next most important elements after the maps. In order to create a Marker:

1. Navigate to the Treweler menu in the admin panel.
2. Click Markers and click the Add New button at the top of the page.

Marker settings include a lot of different options, so let's take a look at each of them.

Map Preview. Map preview can be used to define the location of the marker. If you want to quickly find a place, just use the textbox in the upper right corner of the map preview.

Marker Coordinate. This enables you to set the latitude and longitude of the marker manually. In order to visually set the location of the marker, use the map preview.

Marker Maps. With this drop-down list, you define the location of the marker and on which of the previously created maps will it be displayed. Make sure you have already created, at least, one map according to the instructions from this documentation.

Templates. By using this setting, you can apply one of the templates that have been created previously to the marker. To learn how to create templates, refer to the Templates section of the documentation.

Once a template is chosen, the marker settings will be automatically configured according to the template settings, and the marker settings fields will be disabled.

If you need to add a custom value to any of the fields, click on the lock icon to the right of the field to unlock it and then insert your desired value. In order to make changes to locked values, you need to use the template settings.

General. Here it's possible to enable or disable clustering for the selected marker, change a marker behavior on click, as well as adjust marker offset on click.

In this tab, you can also activate switchers to hide the marker in the locator panel, ignore filters for this marker as well as add a link that will open when clicking on the marker.

Marker Styles. In addition to everything else, the plugin also includes several built-in marker styles. Simply just choose a style that suits your liking, and changes will appear immediately in the map preview. If the built-in marker styles are not enough for you, you can load your own marker in any graphic format, change the size of the custom marker and its alignment.

Popup Styles. By using his group of settings, you can make the marker popup enabled and customize its styles and behavior when the map is initially loaded. Additionally, you can add images for the marker and activate the image gallery as well as enable the popup close icon.

To add additional content to a popup, you can use custom fields in the "Custom Fields" group of settings, which are described in further detail below.

Custom Fields. By utilizing this set of settings, you can add the necessary custom fields for the popup and marker locator, as well as rearrange their order and values.

Text Lables. The plugin allows you to add text label for the selected marker, as well as customize its position and styles.

Categories. Categories provide a helpful way to group all the related Markers together. With this, it is also possible to set one or several categories for each marker. By default, each marker isn’t assigned with a category and displays as, "Uncategorized". To manage categories, you will need to navigate your way to the Treweler menu in the admin panel and click Categories. Keep in mind, the “Uncategorized” category cannot be deleted.

Routes

This extends the functionality of maps and markers to give an in-depth shape to your imagination. In order to create a Route:

1. Navigate to the Treweler menu in the admin panel.
2. Click Routes and click the Add New button at the top of the page.

Routes settings include a lot of different options, so let us take you through them.

Route Maps. With this drop-down list, you define where the route will be displayed on the previously created maps. Do make sure that you have already created at least one map according to the instructions from this documentation, so you can easily put down the routes onto it.

Route Drawing. Draw your route using the draw tools in the upper right corner of the map preview. To get the most accurate route match, draw points at regular intervals. Using the drawing tool, you can use a maximum of 25 points for your route. Here is a quick tutorial on how to draw a route using a drawing tool:

1. Click the Line icon in the upper right corner of the map preview.
2. Click the map to begin drawing a route.
3. Click the final point to complete the route.
4. Use the Match route menu in the upper left corner, depending on what kind of match you need.
5. To add a new point within the route, click on a small point between two large nodes.
6. To delete your route and draw a new one, click the created route and use the Trash icon on the upper right corner of the map.

Route Styles. You can change the style of the route lines using these settings. Once you have, the changes will immediately appear in the map preview.

Import GPX. If drawing the route is not suitable for you, you can simply just import the GPX file. If the import is successful, the route will be displayed in the map preview.

Categories. Just like the categories in all the aforementioned settings, this also provides a helpful way to group all the related Routes together. It is also possible to set one or several categories for each route. However, by default, each route is assigned the "Uncategorized" category. To manage categories, navigate to the Treweler menu in the admin panel and click Categories. Don’t forget that the “Uncategorized” category cannot be deleted.

Shapes

Make maps more visually attractive and informative by drawing various shapes. Using versatile drawing tools that draw lines, polygons, circles, and bezier curves, grab users' attention to certain areas and objects on the map. Customize any shape imaginable and choose from a large selection of style settings. In order to create a Shapes:

1. Navigate to the Treweler menu in the admin panel.
2. Click Shapes and click the Add New button at the top of the page.

Shapes settings include a lot of different options, so let us take you through them.

Shape Maps. With this drop-down list, you define where the shape will be displayed on the previously created maps. Do make sure that you have already created at least one map according to the instructions from this documentation, so you can easily put down the shapes onto it.

Shape Drawing. Draw your shape using one of the draw tools in the upper right corner of the map preview. Here is a quick tutorial on how to draw a shape using a drawing tool:

1. Click on the icon of the required toolin the upper right corner of the map preview.
2. Click the map to begin drawing a shape.
3. Click the final point to complete the shape.
4. To add a new point within the shape, click on a small point between two large nodes.
5. To delete your shape and draw a new one, click the created shape and use the Trash icon on the upper right corner of the map.

Shape Styles. You can change the style of the shape using these settings. To edit styles, draw a new shape using the draw tools in the upper right corner of the map or select an existing shape. Once you have, the changes will immediately appear in the map preview.

Custom Fields

Add an expanded set of information for a specific location using a wide range of custom fields. With the custom fields builder, you can easily customize marker popups and marker locators, create any number of custom fields, edit their values, as well as change their style and order.

Creating custom fields

1. Navigate to the Treweler menu in the admin panel.
2. Click Custom Fields, and then click the Add New button at the top of the page.
3. Select a custom field type and set the name of your custom field.
4. Specify default field values if required.
5. Click the Publish button to save the custom field.

Adding custom fields to the marker popup or locator

1. Once you have created the custom fields, navigate to the Custom Fields tab on the Marker Settings page.
2. Activate the Show Custom Fields switchers in the required tabs.
3. Use the dropdown list and click the Add Fields button in the same row to add custom fields as you need. Change the order of the custom fields if necessary.
4. By default, all custom fields are filled with their default values. To add a custom value for a specific field, go to the Value tab, click on the required lock icon on the right side of the row and add a custom value.
5. Click the Save button to apply changes.

If a template is enabled for a marker, then the list of the custom fields and their order should be set up in the template settings. Within the marker settings, it is only possible to change the custom field values in this case.

Marker Templates

Making a large number of markers in the same style is made so convenient by creating a marker template with your chosen marker style, popup and image settings, text labels, and custom fields settings.

We strongly suggest using templates to make it easier to edit a large number of markers.

Creating marker templates

1. Navigate to the Treweler menu in the Admin panel.
2. Click Templates and click the Add New button at the top of the page.
3. Set the name of the template you are creating, and then, choose and edit your desired template settings in the Template Details section.
4. Click the Publish button to save the new template.

Applying the template to a marker

1. After creating a template, navigate to the Template tab on the Marker Settings page.
2. Select the name of the template you would like to use from the drop-down list. All marker settings will now follow the settings set in the template.
3. To add a custom value for a specific field, click on the lock icon on the right side of the row and set the custom value you would like to add.
4. Click the Save button to apply the changes to the marker.

Store Locator

The Store Locator can be used to show map markers in the vicinity of either the user's current location or in the vicinity of an area chosen by the user on the map. Moreover, upon activating the Extended Marker Locator, a sidebar appears containing a list of markers, detailed information about markers, and a panel with filters.

Enable store locator for a map

1. Navigate to the Treweler menu in the Admin panel.
2. Click Maps and go to the settings of the necessary map.
3. Click the Store Locator tab on the map settings page.
4. Activate the Enable Store Locator switcher and select the required type of locator (Extended or Simple).
5. Customize the locator to your desired specifications by utilizing the advanced settings available.
6. To set up the list and order of necessary filters, navigate to the Filters tab and activate filtering. The list of available filters is formed based on the list of created custom fields as well as the values of these custom fields set for markers. Filtering is only available for Extended Locator type.
7. Click the Publish button to apply changes.

Use the Custom Field tab on the templates and markers settings pages to add content to the Extended Locator sidebar.

Import

With the Treweler import feature, you can easily transfer marker data from a Google spreadsheet to multiple Treweler maps using the Google Sheets API.

To use this functionality, you need a Google Account, configure specific settings in the Google Cloud Platform, as well as create and complete a Google spreadsheet following the provided guidelines below.

Create and apply Google credentials

To enable the import functionality, start by generating a private key within the Google Cloud Platform and then upload it on the plugin settings page.

Creating and applying a private key is a simple process that includes the following steps:

1. Create a new project or use an existing one on the Google Cloud Platform.
2. Enable the Google Sheets API within your selected Google Cloud project.
3. Create a Google service account with the Viewer role.
4. Create a JSON private key for the Google service account.
5. Upload the JSON file with the private key on the Treweler plugin settings page.

In this video tutorial, we'll walk you through the entire process step by step.

Google spreadsheet settings

As the data is imported from a Google spreadsheet, the next step is to create a new one in Google Drive and configure its sharing settings.

1. Create a new spreadsheet in Google Drive.
2. Navigate to File, then click on Share and select Share with others. Change the setting from General access to Anyone with the link.
3. Within the same modal window, switch the role from Viewer to Editor.

In this video, each step will be guided through.

Create imports

Once the basic settings are complete, it's time to create Imports and configure them. Using the plugin, an unlimited number of Imports can be created to transfer information from various sources.

In order to create an Import:

1. Open the WordPress admin panel and go to the Treweler menu.
2. Choose "Import" and then click on the Add New button at the top of the page.

Let's review the different options in the import settings.

Spreadsheet URL or ID. Paste the Google Spreadsheet ID from your browser's address bar (e.g., https://docs.google.com/spreadsheets/d/spreadsheetId/edit#gid=0) into this field. Alternatively, you can simply paste the entire Google Spreadsheet URL, and the plugin will automatically extract its ID.

Sheet ID. Once you paste the correct Spreadsheet ID, you have the option to choose a specific page within the spreadsheet from which data will be imported.

Number of Top Rows Ignored. Using this field, you can specify the number of the first rows of the table to be ignored when importing data. Use this setting if you need to make notes for the columns at the top of the table.

Removal Rule. Using this option, you can choose from different rules to remove existing markers when importing new data.

Google spreadsheet data

To ensure a proper import, it's important to accurately complete the Google spreadsheet according to the provided guidelines. Please keep to the specified column names and data formats detailed below. Any columns containing incorrect names or inaccurate data in the cells will be ignored during the import process.

Main marker fields

Custom fields

The “Field Key” can be found in the list of custom fields or on the settings page for each custom field.

Here's a link to a well-filled Google spreadsheet for reference.

Data Import

After completing all necessary configurations and populating the Google spreadsheet with data, you're ready to initiate the data import.

To start the import procedure, simply click the Run Import button. You'll get a report on created, updated, and removed markers during the import.

Maps Publishing

Depending on your ideas or project needs, there are two ways to publish a map.

Publishing via Shortcode

Copy the shortcode with the necessary settings from the specific Map page and paste it on the page where you feel the need to place the map. Save the changes and check if that the map is displayed correctly.

Such problems can be caused by complex page structure or other theme settings. In this case, make sure that you insert the shortcode into the main container of the template, and not inside other elements.

The most common solution when the map embedded via the shortcode is not displayed is to update the WordPress permalinks. In order to update the WordPress permalinks:

1. Login to your WordPress admin panel.
2. Navigate to the Settings menu and go to the Permalinks page.
3. Click on the button Save Changes at the bottom of the page without any other changes.

This will surely help to avoid problems with the map displaying.

Publishing via Page Settings

This method allows you to display a full-screen map using a WordPress Page. Select or create the page you need to use for a full-screen map. In the page settings, find the Treweler Fullscreen Map drop-down list and select the map that should be displayed at the page URL. Save the changes and check that the map is displayed correctly.

Activate the Custom Settings checkbox if you need to set a custom initial point or initial zoom level.

Save the changes and check that the map is displayed correctly.

List of Credits

Finally, we would like to thank the people who placed their trust in us and made our dreams come true with their credible products. Treweler, most certainly, would not have been possible, if not for their stupendous contributions!

1. Mapbox
2. Bootstrap
3. jQuery
4. Select2
5. Color Picker
6. FontIconPicker
7. Fancybox

Plugin Support

We highly appreciate you reading through this documentation! If you have any more questions related to the plugin, please feel free to contact our support team using the Support tab on the plugin page.

We will be more than happy to assist you!

Developed by Aisconverse